home *** CD-ROM | disk | FTP | other *** search
/ Monster Media 1996 #15 / Monster Media Number 15 (Monster Media)(July 1996).ISO / bbs_door / fnls121.zip / FNLSCAN.DOC < prev    next >
Text File  |  1996-04-13  |  18KB  |  391 lines
  1.  
  2.                     ╖──── ╖────╖ ╖     ╓───
  3.                     ║     ║    ║ ║     ║
  4.                     ║───  ║    ║ ║     ╙───╖ ╓───  ──╖ ╖──╖
  5.                     ║     ║    ║ ║         ║ ║    ╓──║ ║  ║
  6.                     ╜     ╜    ╜ ╜──── ────╜ ╙─── ╙──╜ ╜  ╜
  7.  
  8.                            FNLScan Documentation File
  9.                                   Version 1.21
  10.                      (c) Copyright 1993-1996 - Stacy Smith
  11.  
  12.                                   Courtesy of:
  13.  
  14.                          The Bloom Beacon-Picayune BBS
  15.         Node 1: *** DOWN *** (USRobotics Courier Dual Standard HST/V.34)
  16.                                     FidoNet
  17.                                      ILink
  18.                                     Intelec
  19.  
  20.                                   Stacy Smith
  21.  
  22.  
  23. ┌────────────────────┐
  24. │  1. Introduction:  │
  25. └────────────────────┘
  26.  
  27. FNLScan was developed because many of my users who use Fidonet Netmail kept
  28. coming to me wanting to know if there was a node in such-and-such a place, or
  29. what address this-or-that person was at.  While unzipping the nodelist and
  30. using a text editor to search the nodelist, I groused that I wish they could do
  31. this themselves.  Now they can use FNLScan, the Fidonet NodeList Scan door.
  32.  
  33.  
  34. ┌───────────────────────────┐
  35. │  2. Features of FNLScan:  │
  36. └───────────────────────────┘
  37.  
  38.   ∙ Scans the standard NODELIST.nnn text file (uncompiled nodelist), FTS-0005
  39.     compatible.  This format was chosen since it is available to all Fidonet
  40.     systems, regardless of the mailer or BBS software used.
  41.   ∙ Up to 15 Fidonet-compatible nodelists can be configured for scanning.
  42.   ∙ Fully multi-language capable for PCBoard sysops.
  43.   ∙ Virtually all door text is contained within display or prompt files that
  44.     can be modifed by the sysop for customization and foreign language support.
  45.   ∙ @-variables and @X colors translated inline in the text and display files.
  46.   ∙ OS/2, DESQview and Windows aware, including time slice releasing.
  47.   ∙ Optionally logs all FNLScan operations.
  48.   ∙ Fully multinode and simultaeous multi-user compatible.
  49.   ∙ Supports most BBS software through the use of PCBOARD.SYS, DOOR.SYS,
  50.     CALLINFO.BBS and DORINFOx.DEF door drop files.
  51.   ∙ Supports IRQs 2 through 15 and any COM port address.
  52.   ∙ Supports FOSSIL drivers.
  53.   ∙ Supports Digiboard multiport cards.
  54.   ∙ Written completely in C for optimal speed, using Microsoft C/C++ 7.0.
  55.  
  56.  
  57. ┌─────────────────────────────────────────────────────────┐
  58. │  3. Files Included in the FNLScan Distribution Archive  │
  59. └─────────────────────────────────────────────────────────┘
  60.  
  61.     FNLSCAN.EXE     Fidonet NodeList Scan door program
  62.     FNLSTXT         Default FNLScan text and prompt file
  63.     WELCOME         Text welcome screen file
  64.     MENU            Text menu file
  65.     HELP            Text help file
  66.     CLOSE           Text closing file
  67.     SAMPLE.CFG      Sample FNLScan configuration file
  68.     FNLSCAN.DOC     This file
  69.     SUPPORT.DOC     List of authorized support sites for my shareware
  70.     HISTORY.DOC     FNLScan revision history in reverse order
  71.     REGISTER.FRM    Registration form for FNLScan
  72.     FILE_ID.DIZ     Internal description file
  73.  
  74. When you unzip the distribution archive, you should see my PKZIP authenticity
  75. verification stamp, and a '-AV' after every file in the archive:
  76.  
  77.     # SSU301    The Bloom Beacon-Picayune BBS
  78.  
  79. If there are any files missing or added, or the -AV stamp is missing, the
  80. archive has been tampered with.  It would be advisable to call my BBS (listed
  81. at the top of this document) for the latest version of FNLScan.
  82.  
  83.  
  84. ┌───────────────────────────┐
  85. │  4. Program Requirements  │
  86. └───────────────────────────┘
  87.  
  88. To the best of my knowledge, this door will run on most any machine capable of
  89. running a BBS package.  My BBS setup was PCBoard 15.22M/10 running on a
  90. LANtastic network with DOS, DESQview and OS/2, but other sysops have
  91. successfully implemented FNLScan on a wide variety of hardware and software.
  92.  
  93. FNLScan requires DOS 3.x or later, as it uses DOS SHARE-compatible file reads
  94. and writes.  FNLScan's memory requirements are small (about 120K or so), so it
  95. can be run as a shelled door versus a dropped-to-DOS door, if your software
  96. supports such a mode and you choose to do so.
  97.  
  98.  
  99. ┌───────────────────┐
  100. │  5. Registration  │
  101. └───────────────────┘
  102.  
  103. FNLScan is not free; nor is FNLScan is crippled to force registration.  FNLScan
  104. is fully functional, and will always remain so.  The only variation with the
  105. registered copies is no time delay and beg message.
  106.  
  107. Why register?  Besides a clean conscience, you will get a diskette including
  108. the latest version of FNLScan and a registration key that will work for future
  109. 1.x versions of FNLScan, and will remove the delay and message displayed upon
  110. closing the door.
  111.  
  112. The registration fee for your unique key is $20 for hobby BBS systems.  The
  113. registration fee for commercial BBSs, defined if you run your BBS in the course
  114. of a commercial business (e.g. more than 10 nodes), is $30.  Please print the
  115. file REGISTER.FRM and fill it out.  You can print out the form by issuing the
  116. following command from the DOS prompt:
  117.  
  118.     TYPE REGISTER.FRM > PRN
  119.  
  120.  
  121. ┌───────────────────────────────────────┐
  122. │  6. License, Warranty and Disclaimer  │
  123. └───────────────────────────────────────┘
  124.  
  125. I'll keep this part short and sweet, and dispense with the legal-ese:
  126.  
  127.     License:  You are allowed to use FNLScan for 30 days, after which you must
  128.         either register FNLScan or stop using it completely.  Decompiling,
  129.         disassembly or any other form of reverse engineering FNLScan for any
  130.         purpose is prohibited.  A FNLScan registration is a license for your
  131.         use of FNLScan; I retain ownership of the software.  A single
  132.         registration applies to a single BBS system, regardless of the number
  133.         of computers used in the system.  If you run two or more distinct BBS
  134.         systems on the same computer(s) (with different names), you require two
  135.         or more FNLScan registrations.  FNLScan registrations are not
  136.         transferrable; you cannot sell your registration to another sysop.
  137.         Refer to the registration form for the current pricing structure.
  138.  
  139.     Warranty: There isn't one.  The only thing I'll guarantee is that FNLScan
  140.         will take up disk space, and will disappear when deleted.
  141.  
  142.     Disclaimer: I'm not responsible for anything bad that happens.  FNLScan
  143.         works here, but I cannot be held responsible for it not working on your
  144.         computer or doing any damage to hardware or software.
  145.  
  146. If these aren't agreeable with you, then the best thing to do is delete FNLScan
  147. right now.  I'll do my best to help any user (registered or not) that wants to
  148. use FNLScan, and I'll act on bug reports quickly, but I simply cannot and will
  149. not be responsible for anything bad, like lost data, disk crashes, or whatever
  150. else you can think of.
  151.  
  152.  
  153. ┌───────────────────┐
  154. │  7. Installation  │
  155. └───────────────────┘
  156.  
  157. GENERAL INSTALLATION:
  158. ─────────────────────
  159. Make a subdirectory on your hard drive. For the purposes of this document,
  160. we'll call it "C:\FNLSCAN".  Unarchive the FNLScan distribution archive into
  161. this subdirectory.  You've more than likely already made it this far, if you're
  162. reading this file. <grin>
  163.  
  164. FNLScan opens several files simultaneously for various reasons.  I would
  165. recommend that you have a minimum of FILES=40 or FILES=50 per node in your
  166. system CONFIG.SYS file(s), since FNLScan is run in conjunction with your BBS
  167. software.
  168.  
  169. If you are running under a network or a multitasking operating system, you
  170. should already have DOS's SHARE.EXE loaded.  You must have SHARE loaded or be
  171. running an operating system with SHARE capability (e.g. OS/2, etc.) in order to
  172. take advantage of the file sharing and locking methods used by the FNLScan
  173. program to prevent data loss.  (If you are running a single-node system without
  174. a multitasker, SHARE is not needed).
  175.  
  176. Copy the sample configuration file SAMPLE.CFG to FNLSCAN.CFG and edit to suit
  177. your needs.  Proper configuration will require you to refer to this section and
  178. the section titled "Configuration", which has an in-depth explanation of each
  179. configuration parameter and its function.
  180.  
  181. Note that for the FNLScan program, you can obtain a limited program syntax
  182. screen simply by executing the program name "FNLSCAN".
  183.  
  184. INSTALLATION INTO YOUR BBS SOFTWARE:
  185. ────────────────────────────────────
  186. FNLScan must be run from its own subdirectory; this is required so it can find
  187. the text files required for display.  Only two command-line parameters are
  188. required for FNLScan:
  189.  
  190.     FNLSCAN -Cfnlscan.cfg -Dc:\bbs\door.sys
  191.  
  192. where -C defines the configuration file for FNLScan, and -D is the complete
  193. path and filename of the door drop file.  This should be sufficient for most
  194. BBS systems.  In general, your BBS batch file will look like the following:
  195.  
  196.     CD \FNLSCAN
  197.     FNLSCAN -Cfnlscan.cfg -Dc:\bbs\door.sys
  198.     CD \BBS
  199.     BOARD
  200.  
  201. * NOTE: If you choose to run FNLScan as a shelled door (versus being dropped to
  202.     DOS to open the door), calling the BOARD batch file at the end is
  203.     unnecessary and will hose up the node.
  204.  
  205. If you are running a multinode system, you can use environment variables such
  206. as PCBDRIVE for the drive letter and/or PCBDIR for the subdirectory created by
  207. PCBoard to define the locations of the door drop files.  (Note that PCBDRIVE is
  208. only needed if the door is on a different logical drive that your BBS
  209. software).  This type of door batch file would use the same batch file for all
  210. nodes, and would like something like:
  211.  
  212.     CD \FNLSCAN
  213.     FNLSCAN -Cfnlscan.cfg -D%PCBDRIVE%%PCBDIR%\pcboard.sys
  214.     %PCBDRIVE%
  215.     CD %PCBDIR%
  216.     BOARD
  217.  
  218. If required, you can provide the COM port information directly to FNLScan by
  219. using the -P command switch:
  220.  
  221.     FNLSCAN -Cfnlscan.cfg -Dc:\bbs\door.sys -P2
  222.  
  223. where -P is the port number (1 or 2 for COM1 or COM2, respectively).  If you
  224. need non-standard port support (e.g. COM3, COM4 or different IRQ lines), you
  225. can define the port using the "address,IRQ" format (similar to the DSZPORT
  226. convention), for example:
  227.  
  228.     FNLSCAN -Cfnlscan.cfg -Dc:\bbs\door.sys -P3e8,5
  229.  
  230. FNLScan is capable of using a FOSSIL driver, and automatically detects if you
  231. are running PCBoard /M and uses the appropriate FOSSIL port.  However, if you
  232. need to force FNLScan to use a FOSSIL driver, use the -F command switch with
  233. the FOSSIL port number as the argument:
  234.  
  235.     FNLSCAN -Cfnlscan.cfg -Dc:\bbs\door.sys -F0
  236.  
  237. Remember that the FOSSIL port is zero-based, where COM1 is FOSSIL port 0, COM2
  238. is FOSSIL port 1, etc..
  239.  
  240. FNLScan is also capable of directly accessing a Digiboard multiport I/O card.
  241. This can be defined using the -M command switch with the Digiboard channel
  242. number as the argument:
  243.  
  244.     FNLSCAN -Cfnlscan.cfg -Dc:\bbs\door.sys -M1
  245.  
  246. Note that these parameters can also be passed to the batch file using
  247. environment variables as previously discussed.
  248.  
  249. CUSTOMIZATION OF FNLSCAN TEXT FILES:
  250. ────────────────────────────────────
  251. The FNLSTXT, WELCOME(G), MENU(G), HELP(G) and CLOSE(G) files may be modified by
  252. the sysop if desired.  However, some caveats before you start:
  253.  
  254.   - The files should not be deleted or renamed.  FNLScan expects to find these
  255.     files as named in the currently logged subdirectory.  The sole exception is
  256.     that the files can have different extensions to correlate with your
  257.     multi-lingual setup, if desired and supported (currently, only PCBOARD.SYS
  258.     supports this).
  259.   - The following PCBoard-style @-variables are supported:
  260.         @X##            ANSI replacement color codes
  261.         @BOARDNAME@     BBS name (extracted from registration key)
  262.         @NODE@          Node number
  263.         @SYSDATE@       System date (as of door startup)
  264.         @SYSTIME@       System time (as of door startup)
  265.         @USER@          Full user name
  266.         @FIRST@         User's first name
  267.         @CARRIER@       Carrier speed
  268.         @POS:##@        Set cursor column position
  269.         @SYSOPNAME@     Sysop's name (extracted from registration key)
  270.         @SERIAL@        FNLScan serial number (extracted from registration key)
  271.         @VERSION@       FNLScan version number (#.## format)
  272.   - If @X color codes are used exclusively, the need for "G" versions of the
  273.     various files are not needed; FNLScan will strip them inline if the user is
  274.     not in graphics mode.
  275.   - An ANSI driver is required for proper display of local color codes, as
  276.     FNLScan must translate the @X codes to ANSI.  Note that DESQview users must
  277.     load an ANSI driver within the node windows; an ANSI driver loaded
  278.     externally to DESQview will not be functional!
  279.  
  280.  
  281. ┌────────────────────┐
  282. │  8. Configuration  │
  283. └────────────────────┘
  284.  
  285. The sample configuration file included in the distribution archive is heavily
  286. commented, but some additional information is provided below:
  287.  
  288. DEFAULT_DISP
  289.     FNLScan has two display modes, short and long, requiring one and two lines,
  290.     respectively.  To set your default mode, enter SHORT or LONG.  The user can
  291.     toggle the mode from the FNLScan menu, if he or she desires the other
  292.     format.  Commenting out this parameter is equivalent to setting it to SHORT
  293.     mode.
  294.  
  295. AREACODE_POS and AREACODE_LEN
  296.     The position and length of the area code information within the phone
  297.     number field.  If commented out, these will default to 3 for the U.S.
  298.     format.
  299.         EXAMPLE:  If you phone number is "12 34 567 890", where "12" is the
  300.             areacode, then AREACODE_POS should be set to 1 and AREACODE_LEN set
  301.             to 2.
  302.  
  303. LOG_FILE
  304.     FNLScan can write scanning and error information to a disk log file, if
  305.     desired.  This is the path/filename of the log file for FNLScan to record
  306.     its activities; comment it out if you don't want any disk logging.  I
  307.     strongly recommend that you log the doors operation, as it will greatly
  308.     enhance your ability to debug setup and configuration problems.
  309.  
  310. NODELIST
  311.     The full path and filename, except for the extension, to where your
  312.     UNCOMPILED nodelist is stored.  This must not include an extension! FNLScan
  313.     will search the path defined for the latest version of the nodelist named.
  314.     Up to 15 FTS-0005 compatible nodelists may be defined for sequential
  315.     scanning by FNLScan.  All nodelists must comply with Fidonet standards
  316.     (FTS-0005), specifically that each nodelist must define, at a minimum, one
  317.     zone and one host.  Normally, pointnet lists do not include this
  318.     information, and should not be included in the FNLScan configuration.
  319.  
  320. STATUS_LINE
  321.     If you do not want a status line on the local display when a user is in the
  322.     door, set this parameter to NO.  If you want the status line, enter YES or
  323.     comment out the parameter.  This in conjunction with the DISABLE_FKEYS
  324.     parameter allows you complete control over the access of users who login
  325.     locally.
  326.  
  327. DISABLE_FKEYS
  328.     If you do not want the sysop function keys (e.g. drop to DOS, etc.) active
  329.     during local logins, set this parameter to YES.  Otherwise, enter NO or
  330.     comment it out.
  331.  
  332.  
  333. ┌────────────────────────────┐
  334. │  9. The Future of FNLScan  │
  335. └────────────────────────────┘
  336.  
  337. FNLScan will be supported as long as I'm in the BBSing business (which will be
  338. quite a while...once it's in your blood, you can never shake it <g>).  The
  339. FNLScan system will be continually expanding it's features, so get your
  340. comments in now!  Some current plans:
  341.  
  342.   ∙ Develop code to read compiled nodelist formats (e.g. Version6, Version7,
  343.     Front Door, etc.)...maybe.  A custom index specifically for FNLScan is
  344.     more likely as it will be more efficient.
  345.   ∙ Speed enhancements.
  346.   ∙ Any ideas from you guys?  Thanks! <g>
  347.  
  348. If you have any other suggestions, contact me by U.S. snail-mail or on my BBS
  349. at the number at the top of this document.
  350.  
  351. Thanks for giving FNLScan a try!
  352.  
  353.  
  354. ┌────────────────────────────────┐
  355. │  Appendix A:  DOS Errorlevels  │
  356. └────────────────────────────────┘
  357.  
  358. The following is a list of the errorlevels than can be returned by FNLScan:
  359.  
  360.     0       Successful execution
  361.     99      Help screen (executing a program with no or an insufficient number
  362.             of arguments)
  363.     100     Could not close all open files
  364.     101     Unknown command line parameter
  365.     102     Configuration file not found
  366.     103     Excessive number of nodelists configured
  367.     104     Unable to access nodelist
  368.     105     Unable to intialize door routines
  369.     106     Unable to access FNLSTXT file
  370.     107     Unable to load FNLSTXT into memory
  371.     108     Hobbyist registration node limit (10 nodes) exceeded
  372.     109     Unable to buffer nodelist
  373.     110     Unable to allocate heap memory
  374.     111     Unable to open or lock disk logging file
  375.     200     Undefined error (internal to FNLScan program)
  376.     255     Critical error (internal to FNLScan program)
  377.  
  378.  
  379. ┌─────────────────────────────────────┐
  380. │  Appendix B:  Command Line Summary  │
  381. └─────────────────────────────────────┘
  382.  
  383. FNLSCAN -Cd:\path\config.ext -Dd:\path\door.ext [-P#<,#>] [-F#] [-B#] [-Q]
  384.  
  385.     -C  complete path and filename of the configuration file.
  386.     -D  complete path and filename of the door drop file.
  387.     -P  COM port number [1/2/addr,irq]. (Optional)
  388.     -F  FOSSIL port number. (Optional)
  389.     -B  Digiboard channel number. (Optional)
  390.     -Q  quiets beep on error. (Optional)
  391.